Создание серии промокодов

Запрос позволяет создать заявку на выпуск новой серии промокодов.

Синтаксис запроса

POST https://b2b-api.go.yandex.ru/integration/2.0/promocodes/orders/create

Заголовки запроса

Authorization: Bearer <OAuth-токен>
Процесс получения токена описан в разделе Начало работы.

X-YaTaxi-Selected-Corp-Client-Id — ID клиента из Личного кабинета. Обязателен, если по токену доступно несколько клиентов.

X-Idempotency-Token — токен идемпотентности, строка формата UUID. Одному токену идемпотентности соответствует один заказ, для нового заказа нужно сгенерировать новый токен. Обязательный заголовок.

Тело запроса

Данные о новом заказе промокодов передаются в теле запроса в формате JSON:

Поле	Описание	Формат	Обязательность
`name`	Имя заказа.	Строка	Нет
`max_usages_count`	Максимальное количество поездок по одному промокоду из серии. По умолчанию 1.	Число	Нет
`value`	Номинал одного промокода.	Число	Да
`count`	Количество промокодов.	Число	Да
`service`	Сервис, для которого создаются промокоды. Возможные значения: `taxi`: Такси `grocery`: Лавка `eats`: Еда `fuel`: Заправки `cargo`: Карго По умолчанию `taxi`.	Строка	Нет
`classes`	Список тарифных классов, на которые распространяется промокод в такси. По умолчанию ограничения не устанавливаются.	Массив строк	Нет
`active_from`	Начало действия промокода в формате `ГГГГ-ММ-ДД`. По умолчанию — дата запроса.	Строка	Нет
`active_until`	Конец действия промокода в формате `ГГГГ-ММ-ДД`.	Строка	Да
`bin_ranges`	Массив диапазонов BIN-кодов. Массив элементов, где каждый элемент — пара из начального и конечного значений.	Массив	Нет
`bank_name`	Словарь наименований банка. Список в формате JSON, где ключ — это язык, а значение — наименование банка на этом языке.	Объект	Нет
`geo_restrictions`	Список географических ограничений. Можно ограничить радиус посадки и радиус конечного местоположения. Ограничения из списка объединены условием `ИЛИ`.	Массив объектов	Нет

Структура элемента массива geo_restrictions:

Поле	Описание	Формат
`source`	ID района, в котором можно начать поездку.	Объект
`destination`	ID района, в котором можно завершить поездку.	Объект
`max_intermediate_points`	Максимальное количество промежуточных точек в поездке. По умолчанию 0.	Число

В массиве geo_restrictions обязательно должно быть указано одно из полей source или destination.

Подробнее о создании новых районов см. в разделе Создание нового района.

Структура объектов source и destination:

Поле	Описание	Формат
`geo_restriction_id`	ID района.	Строка

Ограничения и их значения:

Ограничение	Такси	Заправки, Карго	Лавка, Еда
`service`	"taxi"	"fuel", "cargo"	"grocery", "eats"
`value`	Максимальное: 5 000 Минимальное: 100	Максимальное: 5 000 Минимальное: 100	Максимальное: 30 000 Минимальное: 100
`count`	Максимальное: 1 000 Минимальное: 5	Максимальное: 1 000 Минимальное: 5	Максимальное: 1 000 Минимальное: 5
`active_until`	Не более 90 дней. Отсчет идет от даты запроса на создание промокодов.
`max_usages_count`	Максимальное: 20 Минимальное: 1	Максимальное: 20 Минимальное: 1	Максимальное: 20 Минимальное: 1
`name`	Максимум: 256 Минимум: 1	Максимум: 256 Минимум: 1	Максимум: 256 Минимум: 1
`geo_restrictions`	Доступно только для Такси.	—	—
`classes`	Доступно только для Такси.	—	—

Соответствие значений поля classes и тарифных планов:

Класс	Тарифный план
Эконом	`econom`
Комфорт	`business`
Комфорт+	`comfortplus`
Минивэн	`minivan`
Детский	`child_tariff`
Business	`vip`
Premier	`ultimate`
Élite	`maybach`
Cruise	`premium_van`
Велокурьер	`courier_walking`
Экспресс	`express`
Грузовой	`cargo`
Грузовой по часам	`cargo_hour`

Описание полей ответа

В ответе могут содержаться следующие поля:

Поле	Описание	Формат
`id`	Идентификационный номер заказа промокодов.	Строка

Пример запроса

POST https://b2b-api.go.yandex.ru/integration/2.0/promocodes/orders/create
...
Authorization: Bearer <OAuth-token>
X-YaTaxi-Selected-Corp-Client-Id: <client-id>
X-Idempotency-Token: <токен>

{
  "name": "Новый заказ",
  "max_usages_count": 2,
  "value": 220,
  "count": 31,
  "service": "taxi",
  "classes": ["econom"],
  "active_from": "2024-11-22",
  "active_until": "2024-12-01",
  "bin_ranges": [
    ["123400", "123499"],
    ["555000", "555123"]
  ],
  "bank_name": { 
    "ru": "Банк", 
    "en": "The Bank" 
  },
  "geo_restrictions": [
    {
        "max_intermediate_points": 2,
        "source": {
          "geo_restriction_id": "be9...d4a"
        },
        "destination": { 
          "geo_restriction_id": "be9...d4a"
        }
    }
  ]
}

Пример ответа

{
  "order_id": "15с...83d"
}

Возможные коды ответа

Ответ на данный запрос может содержать следующие стандартные HTTP-коды:

200 — запрос выполнен успешно.
400 — в запросе был передан неизвестный параметр или параметр с недопустимым значением.

Была ли статья полезна?

Получение информации о зонах для Такси и Доставки

Отмена заказа промокодов